Vista Goodies in C++: Monitoring the Computer's Power Status

In this Vista Goodies article, I'll demonstrate how to monitor the computer's power status using new notifications that were added to Vista. For apps that may be CPU- or graphics-intensive — such as audio encoders, games, and media players — the ability to monitor the power status lets them be intelligent about power consumption when running on laptops. For example, a media player might automatically stop playing when the battery level falls below 15%, so the user will have plenty of time to attach a power cord, and won't have to scramble to close or stop the player to preserve what little power is left.

This article is written for the RTM version of Vista, using Visual Studio 2005, WTL 7.5, and the Windows SDK. See the introduction in the first Vista Goodies article for more information on where you can download those components.

This article's sample project is a dialog-based app that shows some simple animation. It monitors the computer's power status, updates the display to reflect the current status, and turns off the animation in situations where power conservation is important. For example, here is the dialog showing that the computer is running on AC power:

The "Hello, Bob!" text changes color every second in this case, since the computer isn't in a low-power situation and it's OK to use animation.

Vista defines three default power schemes, named Power saver, Balanced, and High performance. Each scheme is a pre-set group of settings that control things like hard disk spin-down time, the maximum CPU speed to use, and so on. You can choose a power scheme using the battery tray icon or the Power Options control panel applet. Here is the tray selector with the Power saver scheme selected:

Vista also has some settings that can be different when the computer is using different power sources: batteries versus AC power. You can, for example, set the monitor to turn off after 3 minutes on batteries, or 15 minutes on AC power. Vista also monitors the battery power remaining, which is expressed as a percentage from 1 to 100.

Apps can register to be notified of changes to the power scheme, power source, or battery power. The two APIs involved are RegisterPowerSettingNotification() and UnregisterPowerSettingNotification(). The prototype for RegisterPowerSettingNotification() is:

hRecipient is a handle to the object that wants to receive notifications; in our case it's our dialog's HWND. PowerSettingGuid is a GUID that indicates which event we want to be notified of. Flags indicates what type of handle hRecipient is; in this sample code, the handle will always be an HWND, so we'll pass DEVICE_NOTIFY_WINDOW_HANDLE for Flags.

The relevant GUIDs for PowerSettingGuid are:

RegisterPowerSettingNotification() returns an HPOWERNOTIFY, or NULL if an invalid parameter was passed. The HPOWERNOTIFY is only used when unregistering; the actual notifications occur through window messages.

CMainDlg has three HPOWERNOTIFY members:

OnInitDialog() calls RegisterPowerSettingNotification() once for each type of notification. For example, this code registers for notifications about power scheme changes:

If RegisterPowerSettingNotification() fails, it's not a critical error; the app just won't be notified about that particular event.

When an app needs to be notified of a power change, the system sends it a WM_POWERBROADCAST message. WM_POWERBROADCAST is not a new message, but in Vista there is a new event code PBT_POWERSETTINGCHANGE and an associated data structure POWERBROADCAST_SETTING. When a PBT_POWERSETTINGCHANGE notification is sent, the message's lParam points to a POWERBROADCAST_SETTING struct, which looks like this:

PowerSetting is a GUID that indicates what type of event occurred. The possible values for this member are the same GUIDs that are passed to RegisterPowerSettingNotification(). The rest of the struct is a variable-length chunk of data that contains the details of the event. This data varies among the different events:

PowerSetting value

Data description

GUID_POWERSCHEME_PERSONALITY

A GUID that indicates the active power scheme:

GUID_ACDC_POWER_SOURCE

An int that indicates the power source: 0 for AC power, 1 for batteries, or 2 for short-term batteries (for example, batteries in a UPS).

GUID_BATTERY_PERCENTAGE_REMAINING

An int that indicates the battery power remaining: 1 to 100.

CMainDlg has a few members that keep track of the current power situation:

These members are set to reasonable defaults (balanced scheme, not on batteries, animation on) and are changed in the WM_POWERBROADCAST handler. OnPowerBroadcast() starts by checking the event type, and returning if it's not PBT_POWERSETTINGCHANGE:

Next, we get a pointer to the POWERBROADCAST_SETTING struct sent with the message, and look at its PowerSetting member to see what event this notification is for. If it's GUID_POWERSCHEME_PERSONALITY, we determine what the new scheme is. If the scheme isn't one of the three predefined GUIDs, then we'll assume the scheme is Balanced.

For power source notifications, we determine whether the new source is batteries or AC power:

Finally, for battery power notifications, we save the new percentage:

Now that we've updated the static text controls to reflect the new power state, we determine whether to turn the animation on or off. The app's logic is this: